package cz.cuni.mff.ufal.volk.services;

import java.util.List;

import cz.cuni.mff.ufal.volk.Expression;
import cz.cuni.mff.ufal.volk.Speech;
import cz.cuni.mff.ufal.volk.Text;
import cz.cuni.mff.ufal.volk.UnsupportedLanguageException;

/**
 * Text-To-Speech service.
 *
 * @author Bartłomiej Etenkowski
 */
public interface TextToSpeech extends LanguageItemProcessor {

  /**
   * <p>Generates speech from the given text.</p>
   *
   * @param  text the text that has to be converted into speech. If it has the language
   *         property set (see {@link Expression#getLanguage()}
   *         and {@link Expression#setLanguage(String)} methods) the language defined
   *         by the property is used. Otherwise, the service can (but does not have to)
   *         try to recognize the language of the text.
   * @param  voice the name of the voice to be used. It can be {@code null}, if so, the default
   *         voice for the given language will be used
   * @return the generated speech or {@code null} if the requested voice does not exist
   *         or does not support the given language
   *
   * @throws NullPointerException if the text parameter is null
   * @throws UnsupportedLanguageException if the specified language is not supported
   *         by this Text-To-Speech service
   * @throws LanguageNotRecognizedException if the language of the text cannot be recognized
   *         by the service
   * @throws ProcessingException if a processing exception occurred
   */
  Speech process(Text text, String voice);

  /**
   * Retrieves the list of the voices available for the given language.
   *
   * @param  language the language to be checked or {@code null} if one want to retrieve
   *         the list of all available voices
   * @return the list of the available voices for the given language or all available voices
   *         if the language parameter is null. If the given language is not supported
   *         by the service, the method will return an empty list
   */
  List<String> availableVoices(String language);

}
